<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" >
<head>
<title>Line Following using the Maze Simulator</title>
<link href="../Styles/Standard.css" rel="stylesheet" type="text/css" />
</head>
<body>
<table width="100%">
<tr>
<td width="200"><a href="http://www.ProMRDS.com"><img src="../Images/HomeIcon.gif" alt="ProMRDS Home Page" border="0" width="200" height="60" /></a></td>
<td width="*" align="center"><img src="Images/LineFollowing.gif" alt="Line Following" /></td>
</tr>
<tr>
<td colspan="2"><hr /></td>
</tr>
</table>

<div class="page">
<p class="heading"><span class="smallhead">Professional</span><br />&nbsp;&nbsp;&nbsp;Microsoft Robotics Developer Studio<br />
<a href="http://www.ProMRDS.com" onmouseout="Home.src='../Images/Home.gif';" onmouseover="Home.src='../Images/Home_f2.gif';"><img name="Home" src="../Images/Home.gif" width="150" height="25" border="0" alt="Home Page" /></a>
<a href="../ReadMe.htm" onmouseout="Contents.src='../Images/Contents.gif';" onmouseover="Contents.src='../Images/Contents_f2.gif';"><img name="Contents" src="../Images/Contents.gif" width="150" height="25" border="0" alt="Book Contents" /></a>
<a href="ReadMe.htm" onmouseout="ThisChapter.src='../Images/ThisChapter.gif';" onmouseover="ThisChapter.src='../Images/ThisChapter_f2.gif';"><img name="ThisChapter" src="../Images/ThisChapter.gif" width="150" height="25" border="0" alt="This Chapter" /></a>
</p>

<h1>Line Following using the Maze Simulator</h1>

<h2>Background</h2>
<p>
Questions about Line Following in the MRDS Simulator come up from time to time
in the Discussion Forum. This example uses the Maze Simulator. The concept is
very simple -- Make some really tiny walls (only a few millimeters high)
to act as the lines! The result is shown in the screenshot below (click on the
image for larger view):
</p>
<a href="Images/Pioneer-Line-Following.jpg"><img src="images/Pioneer-Line-Following_small.jpg" alt="Line Following using a Pioneer robot" border="0" /></a>
<p>
To set up the Line Following environment there are several steps you need to take:
</p>
<ul>
<li>Create an appropriate bitmap image of your Line Following field.</li>
<li>Edit the Maze Simulator configuration file and change it as appropriate.</li>
<li>Write your own service to use the Webcam to find the lines and the Differential
Drive to control the robot.</li>
</ul>

<h3>Creating a Bitmap Image for Line Following</h3>
<p>
The objective of creating a bitmap image is to specify the lines that the
robot must follow. It only needs to be in two colors -- the background and
the lines. A sample image is shown below (at half size - the full image is 500x500):
</p>
<a href="Images/LineFollowingPlan.gif"><img src="Images/LineFollowingPlan_small.gif" alt="Line Following Plan" border="0" /></a>
<p>
A copy of this image is included with the code. It is called,
not surprisingly, LineFollowing.bmp, and should be in store/media/Maze_Textures.
</p>
<p>
The starting point is in the
bottom left corner, and the finishing point is the circle near the
middle. Notice that there are loops and dead ends. It is not an easy
map to follow.
</p>
<p>
It is difficult to draw smooth curves in a bitmap, and the Maze Simulator
is not very good at handling them because it is designed to work with
straight lines. Robots cannot easily turn 90-degree corners. However, this
just adds to the challenge!
</p>
<p>
As with any maze, the pixel in the top-left corner specifies the background
color (which is grey in this case).
</p>
<h3>Changing the Config File</h3>
<p>
The Maze Simulator configuration is saved in MazeSimulator.Config.xml. This file
should be in the
ProMRDS\Config folder. Note that you should make a backup copy of the existing
config file first!
</p>
<p>
You can edit this file using Notepad.
The following instructions explain the changes to the file, but you do not have
to make them if you use the supplied file.
</p>
<p>
The first thing that needs to be changed is the name of the Maze:<br />
<tt>&lt;Maze&gt;/ProMRDS/Chapter9/MazeSimulator/LineFollowing.bmp&lt;/Maze&gt;</tt><br />
In this example the file should be in the MazeSimulator source folder, but you
can move it somewhere else.
</p>
<p>
You can change the line color if you wish, but line following is usually
done using black lines on a light background (or vice versa). The ground
color can be changed using the texture. The plaster texture is a good
light background:<br />
<tt>&lt;GroundTexture&gt;plaster.jpg&lt;/GroundTexture&gt;</tt><br />
This texture file should already exist in the store\media folder.
</p>
<p>
The color of the lines can be changed using the corresponding entry
in either the WallTextures or WallColors. In the sample config, the
WallTexture is specified as black for the 8th entry in the WallTextures:<br />
<tt>
&lt;WallTextures&gt;<br />
&nbsp;&nbsp;&lt;string&gt;Maze_Textures/SolidBlack.bmp&lt;/string&gt;<br />
&nbsp;&nbsp;&lt;string&gt;Maze_Textures/SolidRed.bmp&lt;/string&gt;<br />
&nbsp;&nbsp;&lt;string&gt;Maze_Textures/SolidLime.bmp&lt;/string&gt;<br />
&nbsp;&nbsp;&lt;string&gt;Maze_Textures/SolidYellow.bmp&lt;/string&gt;<br />
&nbsp;&nbsp;&lt;string&gt;Maze_Textures/SolidBlue.bmp&lt;/string&gt;<br />
&nbsp;&nbsp;&lt;string&gt;Maze_Textures/SolidMagenta.bmp&lt;/string&gt;<br />
&nbsp;&nbsp;&lt;string&gt;Maze_Textures/SolidCyan.bmp&lt;/string&gt;<br />
&nbsp;&nbsp;&lt;string&gt;Maze_Textures/SolidBlack.bmp&lt;/string&gt;<br />
...<br />
&lt;/WallTextures&gt;<br />
</tt>
(The 8th entry corresponds to White, which is the color of the lines in
the bitmap image.)
</p>
<p>
The lines have to be really, really low walls. So change the Height Map
so that the 8th entry is tiny:<br />
<tt>
&lt;HeightMap&gt;<br />
&nbsp;&nbsp;&lt;float&gt;0.005&lt;/float&gt;<br />
&nbsp;&nbsp;&lt;float&gt;5&lt;/float&gt;<br />
&nbsp;&nbsp;&lt;float&gt;10&lt;/float&gt;<br />
&nbsp;&nbsp;&lt;float&gt;8&lt;/float&gt;<br />
&nbsp;&nbsp;&lt;float&gt;10&lt;/float&gt;<br />
&nbsp;&nbsp;&lt;float&gt;15&lt;/float&gt;<br />
&nbsp;&nbsp;&lt;float&gt;15&lt;/float&gt;<br />
&nbsp;&nbsp;&lt;float&gt;0.01&lt;/float&gt;<br />
...<br />
&lt;/HeightMap&gt;<br />
</tt>
</p>
<p>
Side note: The value for black is set to 0.005. If you change the
background color in the bitmap to black, then you can get white lines
on a black background. The background has to be lower than the lines.
This is a special case because black has a pixel value of zero.
</p>
<p>
Notice that the 8th entry is 0.01. Normall this would be 1cm high,
which is still a decent step, so you also need to modify the parameters that
affect the scaling:<br />
<tt>
  &lt;WallBoxSize&gt;0.99&lt;/WallBoxSize&gt;<br />
  &lt;GridSpacing&gt;0.01&lt;/GridSpacing&gt;<br />
  &lt;HeightScale&gt;0.1&lt;/HeightScale&gt;<br />
</tt>
This reduces the height by a further factor of 10. The Grid Spacing is also
reduced so that the pixels in the bitmap only correspond to about 1cm.
</p>
<p>
Lastly, position the robot so that it starts from the correct location.
This is done as follows:<br />
<tt>
  &lt;RobotStartCellRow&gt;280&lt;/RobotStartCellRow&gt;<br />
  &lt;RobotStartCellCol&gt;-180&lt;/RobotStartCellCol&gt;<br />
</tt>
</p>

<h3>Modifying the Maze Simulator's Camera Orientation</h3>
<p>
When the Maze Simulator creates the simulated Pioneer 3DX robot, it places
a webcam on top of the robot. By default, cameras are oriented so that they
look out horizontally. In order to see the floor immediately in front of the
robot, we need to make two changes: Move the camera forward to look over
the front of the robot and tilt it downwards.
</p>
<p>
Edit the config file and change the following settings:<br />
<tt>
&lt;CameraPosition&gt;<br />
&nbsp;&nbsp;&lt;X xmlns="http://schemas.microsoft.com/robotics/2006/07/physicalmodel.html"&gt;0&lt;/X&gt;<br />
&nbsp;&nbsp;&lt;Y xmlns="http://schemas.microsoft.com/robotics/2006/07/physicalmodel.html"&gt;0.5&lt;/Y&gt;<br />
&nbsp;&nbsp;&lt;Z xmlns="http://schemas.microsoft.com/robotics/2006/07/physicalmodel.html"&gt;-0.5&lt;/Z&gt;<br />
&lt;/CameraPosition&gt;<br />
&lt;CameraTiltAngle&gt;-85&lt;/CameraTiltAngle&gt;<br />
</tt>
Note that you do not need to do this if you are using the sample
Line Following config that was supplied.
</p>
<p>
These changes move the camera forwards and angle it down at 85 degrees
(the -85 in the CaneraTiltAngle).
</p>
<p>
You might think that the camera should be angled down at 90 degrees.
However, this causes some strange behavior in the simulator as the
robot rotates. The image in the webcam suddenly jumps as the
orientation of the robot crosses 90 degree boundaries and it gets
confusing. Using 85 degrees is close enough.
</p>

<h2>Requirements and Installation</h2>
<p>
This example is just an application of the Maze Simulator. Therefore you need to
download and install the Maze Simulator first. Make sure that you have this working
before you try to implement Line Following. Then make the minor code change
above and rebuild. If you want to return to the original camera orientation,
just comment out the new lines and recompile again.
</p>
<p>
LineFollowing.bmp should already be in the store\media folder. A
config file called ProMRDS\Config\MazeSimulator.LineFollowing.Config.xml is also supplied.
You need to rename this to MazeSimulator.Config.xml.
You should take a copy of your existing config
file before you overwrite it.
</p>

<h2>How to run Line Following</h2>
<p>
<b>NOTE:</b> There is no code to perform Line Following! This application just
provides the simulation environment you need to do Line Following. The rest is
up to you. You do NOT modify the Maze Simulator service. Instead, write a new
service that connects to a Webcam and a Differential Drive as partners.
</p>
<p>
At the MRDS Command Prompt, enter the following command:<br />
<tt>dsshost -port:50000 -tcpport:50001 -manifest:"ProMRDS/Config/MazeSimulator.manifest.xml"</tt><br />
</p>
<p>
Alternatively, you can run the Maze Simulator from Visual Studio. Regardless of how
you start the Maze Simulator, you must have copied LineFollowing.bmp and
MazeSimulator.Config.xml to the correct folders first.
</p>
<p>
When the Simulator window appears, select the robocam from the Camera menu. You should
see something like the following screenshot:
</p>
<a href="images/Line-Camera-View.jpg"><img src="images/Line-Camera-View_small.jpg" alt="Camera view of a line" border="0" /></a>
<p>
The objects in the window at the bottom are the bumpers at the front of the Pioneer robot.
If you do not want these in the picture, you will have to adjust the Z coordinate
of the camera Position a little more. However, this gives you a point of reference.
</p>
<p>
The T-junction is the start of the Line Following maze. This is where your robot
should begin its journey, so it needs to start out by moving forwards until it
recognizes the line.
</p>
<p>
If you use the Dashboard that comes in the Maze Simulator package, you can connect
to the Pioneer's Differential Drive and also the camera. Try driving the robot around
and following the line yourself. It's not easy!
</p>
<h2>The Challenge</h2>
<p>
Now it is over to you. Write a service that can successfully navigate by following
the lines and locate the circle at the end point. Processing the images should not
be too hard because the black line is very clear. You can either handle the images
yourself or use a package like RoboRealm. (Look in the Dashboard code to see how
to connect to a webcam and capture images.)
</p>

<h2>Legal Stuff</h2>
<p>
Thanks to Jason Summerour at <a href="http://www.roboticsconnection.com">RoboticsConnection</a> for providing a sample line
following plan.
</p>

</div>

<hr />
<div class="footer">
Page maintained by:
<a href="m&#97;&#105;&#108;t&#111;:webmaster&#64;promrds&#46;com">webmaster&#64;promrds.com</a><br />
Last Updated: Mar-2008
</div>

</body>
</html>
